feat(cli): add @videojs/cli docs command for LLM-friendly installation#1214
Open
feat(cli): add @videojs/cli docs command for LLM-friendly installation#1214
Conversation
Introduces `@videojs/cli`, a CLI that serves Video.js documentation from the command line with special handling for the installation page. LLMs and humans can generate framework-specific installation code via flags instead of the interactive web pickers that break in plain text. Key changes: - Extract codegen logic from site React components into pure functions (`site/src/utils/installation/codegen.ts`) shared by both the site and CLI - Add `HumanCase`/`LLMCase` Astro components and Turndown rules so `installation.mdx` serves different content to browsers vs. the LLM markdown pipeline - Create `packages/cli/` with `docs`, `config` commands, interactive prompts via @clack/prompts, and flag parsing via @bomb.sh/args - CLI builds bundled docs from site's LLM markdown output at build time Closes #1185 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for vjs10-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📦 Bundle Size Report🎨 @videojs/html — no changesPresets (7)
Media (8)
Players (3)
Skins (17)
UI Components (23)
Sizes are marginal over the root entry point. ⚛️ @videojs/react — no changesPresets (7)
Media (7)
Skins (14)
UI Components (19)
Sizes are marginal over the root entry point. 🧩 @videojs/core — no changesEntries (8)
🏷️ @videojs/element — no changesEntries (2)
📦 @videojs/store — no changesEntries (3)
🔧 @videojs/utils — no changesEntries (10)
📦 @videojs/spf — no changesEntries (3)
ℹ️ How to interpretAll sizes are standalone totals (minified + brotli).
Run |
Include the CLI package in the linked-versions group so it gets versioned and published alongside the other packages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The CLI depends on site build output, which would drag the entire site build into `build:packages`. Exclude it with a negative filter and add a dedicated `build:cli` step to the CD workflow that runs after packages and CDN builds. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Aligns with other published packages in the monorepo. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix flaky config test mock (stable temp dir instead of per-call Date.now) - Add path traversal guard in readBundledDoc and readLlmsTxt - Validate config keys and values in setConfigValue/getConfigValue - Fix --install-method help text to reflect actual defaults per framework - Add site-aliases test to fail loudly if aliased source files move - Narrow codegen function signatures with Pick<> to remove dummy params - Consolidate __CLI_VERSION__ declaration into env.d.ts - Consolidate Framework type into config.ts - Replace unsafe cast with runtime guard in formatReactInstallation - Derive site path from workspace root in copy-docs.js - Clean up unused imports in config test Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add ambient type stubs for site module imports so tsc can typecheck - Add "types": ["node"] to CLI tsconfig for Node globals - Defer --skin flag resolution until preset is known (fixes wrong skin when --skin is passed without --preset) - Remove per-preset renderer validation (any media type works with any preset; the UI recommends but doesn't enforce) - Make copy-docs.js exit 1 when site/dist is missing - Polish help text, add --help to config subcommand - Add docExistsInAnyFramework early bail, strip llms footer from output - Improve LLM markdown for installation CLI section - Bump CLI version to beta.15, remove plan and design doc - Add docs command integration tests Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit ec049dc. Configure here.
| function safePath(...segments: string[]): string | null { | ||
| const resolved = resolve(DOCS_DIR, ...segments); | ||
| if (!resolved.startsWith(resolve(DOCS_DIR))) return null; | ||
| return resolved; |
There was a problem hiding this comment.
Path traversal bypass in safePath directory check
Low Severity
The safePath function's startsWith check doesn't append a trailing path separator to DOCS_DIR, so a crafted slug can escape the docs directory into a sibling directory whose name shares the same prefix. For example, if DOCS_DIR resolves to /path/to/docs, a slug like ../../docs-other/secret resolves to /path/to/docs-other/secret.md, which passes the startsWith("/path/to/docs") check despite being outside the intended directory. The check needs resolve(DOCS_DIR) + '/' as the prefix.
Reviewed by Cursor Bugbot for commit ec049dc. Configure here.
| process.exit(1); | ||
| } | ||
| return result; | ||
| } |
There was a problem hiding this comment.
Duplicated skin-mapping logic across two files
Low Severity
mapSkinFlag in docs.ts and mapRawSkin in prompts.ts contain nearly identical logic — both map a raw skin string ('default'/'minimal') to a typed Skin value based on whether the use case is audio. The only difference is the second parameter type (preset string vs UseCase enum) and how isAudio is derived. This duplication risks inconsistent fixes if the skin mapping logic changes.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit ec049dc. Configure here.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@videojs/cli, a CLI that serves Video.js docs from the command line with codegen for the installation pageHumanCase/LLMCaseAstro components + Turndown rules for browser vs. LLM content splittingCommands
Before merging: npm setup
npm publish --access publicmanually once frompackages/cli/to create the@videojs/clipackage on the registry@videojs/cli→ Settings → Configure trusted publishing for the GitHub Actions workflow (cd.yml), matching the existing packagesCloses #1185
Closes #1215
Test plan
node packages/cli/dist/index.mjs docs how-to/installation --framework html --preset video --install-method npm— verify HTML install outputnode packages/cli/dist/index.mjs docs how-to/installation --framework react --media hls --install-method pnpm— verify React + HLS outputnode packages/cli/dist/index.mjs docs how-to/installation --framework react --install-method cdn— verify invalid combo errorsnode packages/cli/dist/index.mjs docs --list --framework html— verify llms.txt listingnode packages/cli/dist/index.mjs docs concepts/skins --framework react— verify regular doc passthroughnode packages/cli/dist/index.mjs docs how-to/installation— verify promptspnpm -F site test— 375 tests passpnpm -F @videojs/cli test— 13 tests passpnpm turbo run build --filter=@videojs/cli...— full build chain succeeds🤖 Generated with Claude Code
Note
Medium Risk
Adds a new publishable
@videojs/clipackage and updates release/CD pipelines to build and ship it, which can affect releases and CI if misconfigured. Also refactors installation code generation paths shared between site and CLI, so mistakes could change the installation docs output for users.Overview
Adds a new publishable Node CLI package,
@videojs/cli, that candocs --listfrom per-frameworkllms.txt, print bundled markdown docs, and forhow-to/installationinteractively/flag-driven generate installation code and replace<!-- cli:replace ... -->markers.Refactors installation snippet generation into shared pure utilities under
site/src/utils/installation/(newcodegen.ts+types.ts) and updates the site’s installation components/stores to consume these shared functions/types instead of embedding ad-hoc codegen.Updates the LLM markdown build integration to preserve
LLMCasecontent and emit CLI-replace markers (data-llms-only,data-cli-replace), adjusts the installation doc to includeHumanCase/LLMCasesections, and wires the CLI into monorepo tooling (release-please manifest/config,cd.ymlbuild step, root scripts/tsconfig,commitlintscope, lockfile, and ignores generatedpackages/cli/docs/).Reviewed by Cursor Bugbot for commit ec049dc. Bugbot is set up for automated code reviews on this repo. Configure here.